AI エージェント向け運用ガイド

Claude Code や AI エージェントから coscli を安全かつ効率よく使うためのガイドです。

認証

エージェント環境では COS_SID 環境変数が最もシンプルです。

code:bash

export COS_SID="your_connect_sid"

cos auth whoami # 確認

CI では Secrets に COS_SID を登録し、環境変数で渡します。

code:bash

cos auth login --no-input --sid "$COS_SID"

トークン節約の鉄則

--json --results-only --select を組み合わせて必要最小限のデータだけ受け取ります。

code:bash

# タイトル一覧だけ (最小)

cos page list --project myproject --json --results-only --select 'pages[].title'

# 本文テキストだけ (AI 処理向け)

cos page text "タイトル" --project myproject

# リンク先本文を一括取得 (Smart Context)

cos page context "タイトル" --project myproject --hops 1

詳細: 出力フォーマット

対話プロンプトへの対応

エージェントは対話プロンプトに応答できません。以下の点に注意してください。

--no-input で対話を無効化します。

確認が必要な破壊系コマンド (page delete 等) は --force --no-input を必ず指定します。

code:bash

# NG (エージェント環境で止まる)

cos page delete "タイトル" --project myproject

# OK

cos page delete "タイトル" --force --no-input --project myproject

書き込み前の dry-run

書き込み系コマンドは必ず --dry-run で確認してから本実行します。

code:bash

cos page new "新ページ" --line "本文" --project myproject --dry-run

cos page new "新ページ" --line "本文" --project myproject

sandbox による権限制限

エージェントに必要なコマンドだけを許可するとリスクを最小化できます。

code:bash

# 読み取り専用に制限

cos --enable-commands "page.list,page.get,page.text,page.context,search,project.list" \

page list --project myproject

# 設定ファイルで永続的に制限

cos config set defaultPermission read

cos config set disableCommands '"page.delete","auth.logout"'

詳細: sandbox / 設定ファイル

Smart Context を使った文脈注入

1 コマンドで関連ページ群の本文を AI に一括注入できます。

code:bash

# 起点ページ + 直接リンク先の本文を取得

cos page context "トップページ" --project myproject --hops 1

# 結果を変数に格納して LLM に渡す

CONTEXT=$(cos page context "タイトル" --project myproject --hops 1 --json --results-only --select 'text')

schema でコマンドを動的探索

code:bash

# 利用可能なコマンド一覧をエージェントに渡す

cos schema --json --results-only

# 特定コマンドのフラグを確認

cos schema page edit --json --results-only

終了コードによる分岐

code:bash

cos page get "タイトル" --project myproject --json

case $? in

0) echo "成功" ;;

2) cos auth login --no-input --sid "$COS_SID" ;;

4) cos page new "タイトル" --line "" --project myproject ;;

6) # 楽観ロック競合 → 楽観ロック対処レシピを参照

COMMIT=$(cos page get "タイトル" --project myproject --json --results-only --select 'commitId')

cos page edit "タイトル" --from-file ./content.txt --expect-commit "$COMMIT" --project myproject ;;

7) echo "sandbox 違反: --enable-commands を確認" ;;

esac